<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>dict manual page - Tcl Built-In Commands</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl Commands</a> <small>&gt;</small> dict</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="dict.htm#M2" NAME="L366">NAME</A>
<DL><DD>dict &mdash; Manipulate dictionaries</DD></DL>
<DD><A HREF="dict.htm#M3" NAME="L367">SYNOPSIS</A>
<DL>
</DL>
<DD><A HREF="dict.htm#M4" NAME="L368">DESCRIPTION</A>
<DL class="description">
<DD><A HREF="dict.htm#M5" NAME="L369"><B>dict append </B><I>dictionaryVariable key </I>?<I>string ...</I>?</A>
<DD><A HREF="dict.htm#M6" NAME="L370"><B>dict create </B>?<I>key value ...</I>?</A>
<DD><A HREF="dict.htm#M7" NAME="L371"><B>dict exists </B><I>dictionaryValue key </I>?<I>key ...</I>?</A>
<DD><A HREF="dict.htm#M8" NAME="L372"><B>dict filter </B><I>dictionaryValue filterType arg </I>?<I>arg ...</I>?</A>
<DL class="description">
<DD><A HREF="dict.htm#M9" NAME="L373"><B>dict filter </B><I>dictionaryValue </I><B>key</B> ?<I>globPattern ...</I>?</A>
<DD><A HREF="dict.htm#M10" NAME="L374"><B>dict filter </B><I>dictionaryValue </I><B>script {</B><I>keyVariable valueVariable</I><B>} </B><I>script</I></A>
<DD><A HREF="dict.htm#M11" NAME="L375"><B>dict filter </B><I>dictionaryValue </I><B>value </B>?<I>globPattern ...</I>?</A>
</DL>
<DD><A HREF="dict.htm#M12" NAME="L376"><B>dict for {</B><I>keyVariable valueVariable</I><B>} </B><I>dictionaryValue body</I></A>
<DD><A HREF="dict.htm#M13" NAME="L377"><B>dict get </B><I>dictionaryValue </I>?<I>key ...</I>?</A>
<DD><A HREF="dict.htm#M14" NAME="L378"><B>dict incr </B><I>dictionaryVariable key </I>?<I>increment</I>?</A>
<DD><A HREF="dict.htm#M15" NAME="L379"><B>dict info </B><I>dictionaryValue</I></A>
<DD><A HREF="dict.htm#M16" NAME="L380"><B>dict keys </B><I>dictionaryValue </I>?<I>globPattern</I>?</A>
<DD><A HREF="dict.htm#M17" NAME="L381"><B>dict lappend </B><I>dictionaryVariable key </I>?<I>value ...</I>?</A>
<DD><A HREF="dict.htm#M18" NAME="L382"><B>dict map </B>{<I>keyVariable valueVariable</I>} <I>dictionaryValue body</I></A>
<DD><A HREF="dict.htm#M19" NAME="L383"><B>dict merge </B>?<I>dictionaryValue ...</I>?</A>
<DD><A HREF="dict.htm#M20" NAME="L384"><B>dict remove </B><I>dictionaryValue </I>?<I>key ...</I>?</A>
<DD><A HREF="dict.htm#M21" NAME="L385"><B>dict replace </B><I>dictionaryValue </I>?<I>key value ...</I>?</A>
<DD><A HREF="dict.htm#M22" NAME="L386"><B>dict set </B><I>dictionaryVariable key </I>?<I>key ...</I>? <I>value</I></A>
<DD><A HREF="dict.htm#M23" NAME="L387"><B>dict size </B><I>dictionaryValue</I></A>
<DD><A HREF="dict.htm#M24" NAME="L388"><B>dict unset </B><I>dictionaryVariable key </I>?<I>key ...</I>?</A>
<DD><A HREF="dict.htm#M25" NAME="L389"><B>dict update </B><I>dictionaryVariable key varName </I>?<I>key varName ...</I>? <I>body</I></A>
<DD><A HREF="dict.htm#M26" NAME="L390"><B>dict values </B><I>dictionaryValue </I>?<I>globPattern</I>?</A>
<DD><A HREF="dict.htm#M27" NAME="L391"><B>dict with </B><I>dictionaryVariable </I>?<I>key ...</I>? <I>body</I></A>
</DL>
<DD><A HREF="dict.htm#M28" NAME="L392">DICTIONARY VALUES</A>
<DD><A HREF="dict.htm#M29" NAME="L393">EXAMPLES</A>
<DD><A HREF="dict.htm#M30" NAME="L394">SEE ALSO</A>
<DD><A HREF="dict.htm#M31" NAME="L395">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
dict &mdash; Manipulate dictionaries
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>dict </B><I>option arg </I>?<I>arg ...</I>?<BR>
<H3><A NAME="M4">DESCRIPTION</A></H3>
Performs one of several operations on dictionary values or variables
containing dictionary values (see the <B><A HREF="#M28">DICTIONARY VALUES</A></B> section
below for a description), depending on <I>option</I>.  The legal
<I>option</I>s (which may be abbreviated) are:
<P>
<DL class="description">
<DT><A NAME="M5"><B>dict append </B><I>dictionaryVariable key </I>?<I>string ...</I>?</A><DD>
This appends the given string (or strings) to the value that the given
key maps to in the dictionary value contained in the given variable,
writing the resulting dictionary value back to that variable.
Non-existent keys are treated as if they map to an empty string. The
updated dictionary value is returned.
<P><DT><A NAME="M6"><B>dict create </B>?<I>key value ...</I>?</A><DD>
Return a new dictionary that contains each of the key/value mappings
listed as arguments (keys and values alternating, with each key being
followed by its associated value.)
<P><DT><A NAME="M7"><B>dict exists </B><I>dictionaryValue key </I>?<I>key ...</I>?</A><DD>
This returns a boolean value indicating whether the given key (or path
of keys through a set of nested dictionaries) exists in the given
dictionary value. This returns a true value exactly when <B>dict
get</B> on that path will succeed.
<P><DT><A NAME="M8"><B>dict filter </B><I>dictionaryValue filterType arg </I>?<I>arg ...</I>?</A><DD>
This takes a dictionary value and returns a new dictionary that
contains just those key/value pairs that match the specified filter
type (which may be abbreviated.)  Supported filter types are:
<P>
<DL class="description">
<DT><A NAME="M9"><B>dict filter </B><I>dictionaryValue </I><B>key</B> ?<I>globPattern ...</I>?</A><DD>
The key rule only matches those key/value pairs whose keys match any
of the given patterns (in the style of <B><A HREF="../TclCmd/string.htm">string match</A></B>.)
<P><DT><A NAME="M10"><B>dict filter </B><I>dictionaryValue </I><B>script {</B><I>keyVariable valueVariable</I><B>} </B><I>script</I></A><DD>
The script rule tests for matching by assigning the key to the
<I>keyVariable</I> and the value to the <I>valueVariable</I>, and then evaluating
the given script which should result in a boolean value (with the
key/value pair only being included in the result of the <B>dict
filter</B> when a true value is returned.)  Note that the first
argument after the rule selection word is a two-element list.  If the
<I>script</I> returns with a condition of <B><A HREF="../TclCmd/catch.htm">TCL_BREAK</A></B>, no further
key/value pairs are considered for inclusion in the resulting
dictionary, and a condition of <B><A HREF="../TclCmd/catch.htm">TCL_CONTINUE</A></B> is equivalent to a false
result. The key/value pairs are tested in the order in which the keys
were inserted into the dictionary.
<P><DT><A NAME="M11"><B>dict filter </B><I>dictionaryValue </I><B>value </B>?<I>globPattern ...</I>?</A><DD>
The value rule only matches those key/value pairs whose values match any
of the given patterns (in the style of <B><A HREF="../TclCmd/string.htm">string match</A></B>.)
<P></DL>
<P><DT><A NAME="M12"><B>dict for {</B><I>keyVariable valueVariable</I><B>} </B><I>dictionaryValue body</I></A><DD>
This command takes three arguments, the first a two-element list of
variable names (for the key and value respectively of each mapping in
the dictionary), the second the dictionary value to iterate across,
and the third a script to be evaluated for each mapping with the key
and value variables set appropriately (in the manner of <B><A HREF="../TclCmd/foreach.htm">foreach</A></B>.)
The result of the command is an empty string. If any evaluation of the
body generates a <B><A HREF="../TclCmd/catch.htm">TCL_BREAK</A></B> result, no further pairs from the
dictionary will be iterated over and the <B>dict for</B> command will
terminate successfully immediately. If any evaluation of the body
generates a <B><A HREF="../TclCmd/catch.htm">TCL_CONTINUE</A></B> result, this shall be treated exactly like a
normal <B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B> result. The order of iteration is the order in
which the keys were inserted into the dictionary.
<P><DT><A NAME="M13"><B>dict get </B><I>dictionaryValue </I>?<I>key ...</I>?</A><DD>
Given a dictionary value (first argument) and a key (second argument),
this will retrieve the value for that key. Where several keys are
supplied, the behaviour of the command shall be as if the result of
<B>dict get $dictVal $key</B> was passed as the first argument to
<B>dict get</B> with the remaining arguments as second (and possibly
subsequent) arguments. This facilitates lookups in nested
dictionaries. For example, the following two commands are equivalent:
<P>
<PRE>dict get $dict foo bar spong
dict get [dict get [dict get $dict foo] bar] spong</PRE>
<P>
If no keys are provided, <B>dict get</B> will return a list containing pairs of
elements in a manner similar to <B><A HREF="../TclCmd/array.htm">array get</A></B>. That is, the first
element of each pair would be the key and the second element would be
the value for that key.
<P>It is an error to attempt to retrieve a value for a key that is not
present in the dictionary.
<P><DT><A NAME="M14"><B>dict incr </B><I>dictionaryVariable key </I>?<I>increment</I>?</A><DD>
This adds the given increment value (an integer that defaults to 1 if
not specified) to the value that the given key maps to in the
dictionary value contained in the given variable, writing the
resulting dictionary value back to that variable. Non-existent keys
are treated as if they map to 0. It is an error to increment a value
for an existing key if that value is not an integer. The updated
dictionary value is returned.
<P><DT><A NAME="M15"><B>dict info </B><I>dictionaryValue</I></A><DD>
This returns information (intended for display to people) about the
given dictionary though the format of this data is dependent on the
implementation of the dictionary. For dictionaries that are
implemented by hash tables, it is expected that this will return the
string produced by <B><A HREF="../TclLib/Hash.htm">Tcl_HashStats</A></B>, similar to <B><A HREF="../TclCmd/array.htm">array statistics</A></B>.
<P><DT><A NAME="M16"><B>dict keys </B><I>dictionaryValue </I>?<I>globPattern</I>?</A><DD>
Return a list of all keys in the given dictionary value. If a pattern
is supplied, only those keys that match it (according to the rules of
<B><A HREF="../TclCmd/string.htm">string match</A></B>) will be returned. The returned keys will be in the
order that they were inserted into the dictionary.
<P><DT><A NAME="M17"><B>dict lappend </B><I>dictionaryVariable key </I>?<I>value ...</I>?</A><DD>
This appends the given items to the list value that the given key maps
to in the dictionary value contained in the given variable, writing
the resulting dictionary value back to that variable. Non-existent
keys are treated as if they map to an empty list, and it is legal for
there to be no items to append to the list. It is an error for the
value that the key maps to to not be representable as a list. The
updated dictionary value is returned.
<P><DT><A NAME="M18"><B>dict map </B>{<I>keyVariable valueVariable</I>} <I>dictionaryValue body</I></A><DD>
This command applies a transformation to each element of a dictionary,
returning a new dictionary. It takes three arguments: the first is a
two-element list of variable names (for the key and value respectively of each
mapping in the dictionary), the second the dictionary value to iterate across,
and the third a script to be evaluated for each mapping with the key and value
variables set appropriately (in the manner of <B><A HREF="../TclCmd/lmap.htm">lmap</A></B>). In an iteration
where the evaluated script completes normally (<B><A HREF="../TclCmd/catch.htm">TCL_OK</A></B>, as opposed to an
<B><A HREF="../TclCmd/error.htm">error</A></B>, etc.) the result of the script is put into an accumulator
dictionary using the key that is the current contents of the <I>keyVariable</I>
variable at that point. The result of the <B>dict map</B> command is the
accumulator dictionary after all keys have been iterated over.
<P>
If the evaluation of the body for any particular step generates a <B><A HREF="../TclCmd/break.htm">break</A></B>,
no further pairs from the dictionary will be iterated over and the <B>dict
map</B> command will terminate successfully immediately. If the evaluation of
the body for a particular step generates a <B><A HREF="../TclCmd/continue.htm">continue</A></B> result, the current
iteration is aborted and the accumulator dictionary is not modified. The order
of iteration is the natural order of the dictionary (typically the order in
which the keys were added to the dictionary; the order is the same as that
used in <B>dict for</B>).
<P><DT><A NAME="M19"><B>dict merge </B>?<I>dictionaryValue ...</I>?</A><DD>
Return a dictionary that contains the contents of each of the
<I>dictionaryValue</I> arguments.  Where two (or more) dictionaries
contain a mapping for the same key, the resulting dictionary maps that
key to the value according to the last dictionary on the command line
containing a mapping for that key.
<P><DT><A NAME="M20"><B>dict remove </B><I>dictionaryValue </I>?<I>key ...</I>?</A><DD>
Return a new dictionary that is a copy of an old one passed in as
first argument except without mappings for each of the keys listed.
It is legal for there to be no keys to remove, and it also legal for
any of the keys to be removed to not be present in the input
dictionary in the first place.
<P><DT><A NAME="M21"><B>dict replace </B><I>dictionaryValue </I>?<I>key value ...</I>?</A><DD>
Return a new dictionary that is a copy of an old one passed in as
first argument except with some values different or some extra
key/value pairs added. It is legal for this command to be called with
no key/value pairs, but illegal for this command to be called with a
key but no value.
<P><DT><A NAME="M22"><B>dict set </B><I>dictionaryVariable key </I>?<I>key ...</I>? <I>value</I></A><DD>
This operation takes the name of a variable containing a dictionary
value and places an updated dictionary value in that variable
containing a mapping from the given key to the given value. When
multiple keys are present, this operation creates or updates a chain
of nested dictionaries. The updated dictionary value is returned.
<P><DT><A NAME="M23"><B>dict size </B><I>dictionaryValue</I></A><DD>
Return the number of key/value mappings in the given dictionary value.
<P><DT><A NAME="M24"><B>dict unset </B><I>dictionaryVariable key </I>?<I>key ...</I>?</A><DD>
This operation (the companion to <B>dict set</B>) takes the name of a
variable containing a dictionary value and places an updated
dictionary value in that variable that does not contain a mapping for
the given key. Where multiple keys are present, this describes a path
through nested dictionaries to the mapping to remove. At least one key
must be specified, but the last key on the key-path need not exist.
All other components on the path must exist. The updated dictionary
value is returned.
<P><DT><A NAME="M25"><B>dict update </B><I>dictionaryVariable key varName </I>?<I>key varName ...</I>? <I>body</I></A><DD>
Execute the Tcl script in <I>body</I> with the value for each <I>key</I>
(as found by reading the dictionary value in <I>dictionaryVariable</I>)
mapped to the variable <I>varName</I>. There may be multiple
<I>key</I>/<I>varName</I> pairs. If a <I>key</I> does not have a mapping,
that corresponds to an unset <I>varName</I>. When <I>body</I>
terminates, any changes made to the <I>varName</I>s is reflected back
to the dictionary within <I>dictionaryVariable</I> (unless
<I>dictionaryVariable</I> itself becomes unreadable, when all updates
are silently discarded), even if the result of <I>body</I> is an error
or some other kind of exceptional exit. The result of <B>dict
update</B> is (unless some kind of error occurs) the result of the
evaluation of <I>body</I>.
<P>
Each <I>varName</I> is mapped in the scope enclosing the <B>dict update</B>;
it is recommended that this command only be used in a local scope
(<B><A HREF="../TclCmd/proc.htm">proc</A></B>edure, lambda term for <B><A HREF="../TclCmd/apply.htm">apply</A></B>, or method). Because of
this, the variables set by <B>dict update</B> will continue to
exist after the command finishes (unless explicitly <B><A HREF="../TclCmd/unset.htm">unset</A></B>).
Note that the mapping of values to variables
does not use traces; changes to the <I>dictionaryVariable</I>'s
contents only happen when <I>body</I> terminates.
<P><DT><A NAME="M26"><B>dict values </B><I>dictionaryValue </I>?<I>globPattern</I>?</A><DD>
Return a list of all values in the given dictionary value. If a
pattern is supplied, only those values that match it (according to the
rules of <B><A HREF="../TclCmd/string.htm">string match</A></B>) will be returned. The returned values
will be in the order of that the keys associated with those values
were inserted into the dictionary.
<P><DT><A NAME="M27"><B>dict with </B><I>dictionaryVariable </I>?<I>key ...</I>? <I>body</I></A><DD>
Execute the Tcl script in <I>body</I> with the value for each key in
<I>dictionaryVariable</I> mapped (in a manner similarly to <B>dict
update</B>) to a variable with the same name. Where one or more
<I>key</I>s are available, these indicate a chain of nested
dictionaries, with the innermost dictionary being the one opened out
for the execution of <I>body</I>. As with <B>dict update</B>, making
<I>dictionaryVariable</I> unreadable will make the updates to the
dictionary be discarded, and this also happens if the contents of
<I>dictionaryVariable</I> are adjusted so that the chain of
dictionaries no longer exists. The result of <B>dict with</B> is
(unless some kind of error occurs) the result of the evaluation of
<I>body</I>.
<P>
The variables are mapped in the scope enclosing the <B>dict with</B>;
it is recommended that this command only be used in a local scope
(<B><A HREF="../TclCmd/proc.htm">proc</A></B>edure, lambda term for <B><A HREF="../TclCmd/apply.htm">apply</A></B>, or method). Because of
this, the variables set by <B>dict with</B> will continue to
exist after the command finishes (unless explicitly <B><A HREF="../TclCmd/unset.htm">unset</A></B>).
Note that the mapping of values to variables does not use
traces; changes to the <I>dictionaryVariable</I>'s contents only happen
when <I>body</I> terminates.
<P>If the <I>dictionaryVariable</I> contains a value that is not a dictionary at
the point when the <I>body</I> terminates (which can easily happen if the name
is the same as any of the keys in dictionary) then an error occurs at that
point. This command is thus not recommended for use when the keys in the
dictionary are expected to clash with the <I>dictionaryVariable</I> name
itself. Where the contained key does map to a dictionary, the net effect is to
combine that inner dictionary into the outer dictionary; see the
<B><A HREF="#M29">EXAMPLES</A></B> below for an illustration of this.
<P></DL>
<H3><A NAME="M28">DICTIONARY VALUES</A></H3>
Dictionaries are values that contain an efficient, order-preserving
mapping from arbitrary keys to arbitrary values.
Each key in the dictionary maps to a single value.
They have a textual format that is exactly that of any list with an
even number of elements, with each mapping in the dictionary being
represented as two items in the list. When a command takes a
dictionary and produces a new dictionary based on it (either returning
it or writing it back into the variable that the starting dictionary
was read from) the new dictionary will have the same order of keys,
modulo any deleted keys and with new keys added on to the end.
When a string is interpreted as a dictionary and it would otherwise
have duplicate keys, only the last value for a particular key is used;
the others are ignored, meaning that,
&ldquo;apple banana&rdquo;
and
&ldquo;apple carrot apple banana&rdquo;
are equivalent dictionaries (with different string representations).
<P>
Operations that derive a new dictionary from an old one (e.g., updates
like <B>dict set</B> and <B>dict unset</B>) preserve the order of keys
in the dictionary. The exceptions to this are for any new keys they
add, which are appended to the sequence, and any keys that are
removed, which are excised from the order.
<H3><A NAME="M29">EXAMPLES</A></H3>
Basic dictionary usage:
<P>
<PRE># Make a dictionary to map extensions to descriptions
set filetypes [<B>dict create</B> .txt &quot;Text File&quot; .tcl &quot;Tcl File&quot;]

# Add/update the dictionary
<B>dict set</B> filetypes .tcl &quot;Tcl Script&quot;
<B>dict set</B> filetypes .tm  &quot;Tcl Module&quot;
<B>dict set</B> filetypes .gif &quot;GIF Image&quot;
<B>dict set</B> filetypes .png &quot;PNG Image&quot;

# Simple read from the dictionary
set ext &quot;.tcl&quot;
set desc [<B>dict get</B> $filetypes $ext]
puts &quot;$ext is for a $desc&quot;

# Somewhat more complex, with existence test
foreach filename [glob *] {
    set ext [file extension $filename]
    if {[<B>dict exists</B> $filetypes $ext]} {
        puts &quot;$filename is a [<B>dict get</B> $filetypes $ext]&quot;
    }
}</PRE>
<P>
Constructing and using nested dictionaries:
<P>
<PRE># Data for one employee
<B>dict set</B> employeeInfo 12345-A forenames &quot;Joe&quot;
<B>dict set</B> employeeInfo 12345-A surname   &quot;Schmoe&quot;
<B>dict set</B> employeeInfo 12345-A street &quot;147 Short Street&quot;
<B>dict set</B> employeeInfo 12345-A city   &quot;Springfield&quot;
<B>dict set</B> employeeInfo 12345-A phone  &quot;555-1234&quot;
# Data for another employee
<B>dict set</B> employeeInfo 98372-J forenames &quot;Anne&quot;
<B>dict set</B> employeeInfo 98372-J surname   &quot;Other&quot;
<B>dict set</B> employeeInfo 98372-J street &quot;32995 Oakdale Way&quot;
<B>dict set</B> employeeInfo 98372-J city   &quot;Springfield&quot;
<B>dict set</B> employeeInfo 98372-J phone  &quot;555-8765&quot;
# The above data probably ought to come from a database...

# Print out some employee info
set i 0
puts &quot;There are [<B>dict size</B> $employeeInfo] employees&quot;
<B>dict for</B> {id info} $employeeInfo {
    puts &quot;Employee #[incr i]: $id&quot;
    <B>dict with</B> info {
        puts &quot;   Name: $forenames $surname&quot;
        puts &quot;   Address: $street, $city&quot;
        puts &quot;   Telephone: $phone&quot;
    }
}
# Another way to iterate and pick out names...
foreach id [<B>dict keys</B> $employeeInfo] {
    puts &quot;Hello, [<B>dict get</B> $employeeInfo $id forenames]!&quot;
}</PRE>
<P>
A localizable version of <B><A HREF="../TclCmd/string.htm">string toupper</A></B>:
<P>
<PRE># Set up the basic C locale
set capital [<B>dict create</B> C [<B>dict create</B>]]
foreach c [split {abcdefghijklmnopqrstuvwxyz} &quot;&quot;] {
    <B>dict set</B> capital C $c [string toupper $c]
}

# English locales can luckily share the &quot;C&quot; locale
<B>dict set</B> capital en [<B>dict get</B> $capital C]
<B>dict set</B> capital en_US [<B>dict get</B> $capital C]
<B>dict set</B> capital en_GB [<B>dict get</B> $capital C]

# ... and so on for other supported languages ...

# Now get the mapping for the current locale and use it.
set upperCaseMap [<B>dict get</B> $capital $env(LANG)]
set upperCase [string map $upperCaseMap $string]</PRE>
<P>
Showing the detail of <B>dict with</B>:
<P>
<PRE>proc sumDictionary {varName} {
    upvar 1 $varName vbl
    foreach key [<B>dict keys</B> $vbl] {
        # Manufacture an entry in the subdictionary
        <B>dict set</B> vbl $key total 0
        # Add the values and remove the old
        <B>dict with</B> vbl $key {
            set total [expr {$x + $y + $z}]
            unset x y z
        }
    }
    puts &quot;last total was $total, for key $key&quot;
}

set myDict {
    a {x 1 y 2 z 3}
    b {x 6 y 5 z 4}
}

sumDictionary myDict
#    prints: <I>last total was 15, for key b</I>

puts &quot;dictionary is now &#92;&quot;$myDict&#92;&quot;&quot;
#    prints: <I>dictionary is now &quot;a {total 6} b {total 15}&quot;</I></PRE>
<P>
When <B>dict with</B> is used with a key that clashes with the name of the
dictionary variable:
<P>
<PRE>set foo {foo {a b} bar 2 baz 3}
<B>dict with</B> foo {}
puts $foo
#    prints: <I>a b foo {a b} bar 2 baz 3</I></PRE>
<H3><A NAME="M30">SEE ALSO</A></H3>
<B><A HREF="../TclCmd/append.htm">append</A></B>, <B><A HREF="../TclCmd/array.htm">array</A></B>, <B><A HREF="../TclCmd/foreach.htm">foreach</A></B>, <B><A HREF="../TclCmd/incr.htm">incr</A></B>, <B><A HREF="../TclCmd/list.htm">list</A></B>, <B><A HREF="../TclCmd/lappend.htm">lappend</A></B>, <B><A HREF="../TclCmd/lmap.htm">lmap</A></B>, <B><A HREF="../TclCmd/set.htm">set</A></B>
<H3><A NAME="M31">KEYWORDS</A></H3>
<A href="../Keywords/D.htm#dictionary">dictionary</A>, <A href="../Keywords/C.htm#create">create</A>, <A href="../Keywords/U.htm#update">update</A>, <A href="../Keywords/L.htm#lookup">lookup</A>, <A href="../Keywords/I.htm#iterate">iterate</A>, <A href="../Keywords/F.htm#filter">filter</A>, <A href="../Keywords/M.htm#map">map</A>
<div class="copy">Copyright &copy; 2003 Donal K. Fellows
</div>
</BODY></HTML>
